独習PHP:第11章 高度なプログラミング
11.3 ドキュメンテーションコメント
クラスや関数の直前に記述し、説明を記載するために特定のルールに則ったコメントのこと。
phpDocumentatorと呼ばれるツールを通すと整形でき、メンテナンス性に優れる。
code:php
// こんな感じのやつ
/**
* メンバに関する情報管理
*
* @author WINGSプロジェクト <wings@example.com>
* @version 1.0
* @license GPL
*/
class Person {
/**
* 名前
*/
private string $name;
/**
* 名前でオブジェクトを初期化する
* @param string $name 名前
* @throws InvalidArgumentException 名前が0文字の場合
*/
public function __construct (string $name) { ... }
}
タグの種類も色々。P618参照。
@paramは引数, @returnは戻り値の属性など。
本家
https://phpdoc.org/
インストールして使用することで、ファイルのドキュメントを簡単に作成できる
各種説明について
code:php
/**
* メソッドを一言で説明する
*
* 説明が足りなければこちらに記述。
* 1行開けるのが好ましい
* // @param: メソッドの引数の説明など。
// @return: 返り値の説明など。
* @param